---
type: integration
title: '@astrojs/netlify'
description: 了解如何使用 @astrojs/netlify 适配器来部署 Astro 项目。
sidebar:
  label: Netlify
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/netlify/'
category: adapter
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import Since from '~/components/Since.astro';

此适配器允许 Astro 将你的 [按需渲染路由及其功能](/zh-cn/guides/on-demand-rendering/) 部署到 [Netlify](https://www.netlify.com/)，包括 [服务器群岛](/zh-cn/guides/server-islands/)，[actions](/zh-cn/guides/actions/) 以及 [sessions](/zh-cn/guides/sessions/)。

如果你需要额外的、需要服务器参与的 Netlify 功能（例如 [Netlify 图片 CDN](#netlify-图片-cdn-支持)），那么你会需要用上此适配器，但如果你只是将 Astro 作为静态的站点构建器，则不需要适配器。

在我们的 [Netlify 部署指南](/zh-cn/guides/deploy/netlify/) 中学习如何部署你的 Astro 网站。

## 为什么是 Astro Netlify

[Netlify](https://www.netlify.com/) 是一个部署平台，允许你通过直接连接 GitHub 仓库来托管你的网站。这个适配器增强了 Astro 的构建流程，为通过 Netlify 部署项目做好准备。

## 安装

Astro 包含了一个 `astro add` 命令，用于自动设置官方集成。如果你愿意，可以改为 [手动安装集成](#手动安装)。

在 Astro 项目中使用以下 `asrto add` 命令添加 Netlify 适配器，以启用按需渲染。这将安装 `@astrojs/netlify` 并一步到位地对你的 `astro.config.mjs` 文件进行相应的更改。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm run astro add netlify
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add netlify
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add netlify
  ```
  </Fragment>
</PackageManagerTabs>

现在，你可以启用 [对每个页面的按需渲染](/zh-cn/guides/on-demand-rendering/#启用按需渲染)，或者将你的构建输出配置设置为 `output: 'server'` 从而 [默认对所有页面都进行服务器端渲染](/zh-cn/guides/on-demand-rendering/#server-模式)。

### 手动安装

首先，使用适合你的包管理器将 Netlify 适配器安装到你的项目依赖中：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/netlify
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/netlify
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/netlify
  ```
  </Fragment>
</PackageManagerTabs>

然后，将适配器添加到 `astro.config.*` 文件中：

   ```js title="astro.config.mjs" ins={2, 6}
    import { defineConfig } from 'astro/config';
    import netlify from '@astrojs/netlify';

    export default defineConfig({
       // ...
       adapter: netlify(),
    });
   ```

## 用法

[阅读完整的部署指南](/zh-cn/guides/deploy/netlify/)

按照指南 [在本地构建你的站点](/zh-cn/guides/deploy/#在本地构建站点)。构建完成后，你将会有一个包含 [Netlify Functions](https://docs.netlify.com/functions/overview/) 的 `.netlify/` 文件夹，其中包含 `.netlify/functions-internal/` 文件夹中的函数和 `.netlify/edge-functions/` 文件夹中的 [Netlify Edge Functions](https://docs.netlify.com/edge-functions/overview/)。

要部署你的站点，请安装 [Netlify CLI](https://docs.netlify.com/cli/get-started/) 并运行：

```sh
netlify deploy
```

这篇 [Netlify 博客文章](https://www.netlify.com/blog/how-to-deploy-astro/) 和 [Netlify 文档](https://docs.netlify.com/integrations/frameworks/astro/) 提供了更多关于如何使用这个集成部署到 Netlify 的信息。

### 在 Netlify Edge Functions 上运行 Astro 中间件

任何 Astro 中间件都会在构建时应用于预渲染页面，在运行时应用于按需渲染页面。

要在预渲染页面上实现重定向、访问控制或自定义响应头，请通过启用 [`edgeMiddleware` 选项](/zh-cn/reference/adapter-reference/#edgemiddleware) 在 Netlify Edge Functions 上运行你的中间件：

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    edgeMiddleware: true,
  }),
});
```

当 `edgeMiddleware` 启用时，边缘函数将为所有请求执行你的中间件代码，包括静态资源、预渲染页面和按需渲染页面。

对于按需渲染的页面，`context.locals` 对象会被 JSON 序列化并通过标头发送给无服务器函数，由该函数执行渲染。作为安全措施，除非请求来自生成的边缘函数，否则无服务器函数将拒绝服务，并返回 `403 Forbidden` 响应。

### 从你的站点访问 edge 上下文

Netlify Edge Functions 提供了一个 [context 对象](https://docs.netlify.com/edge-functions/api/#netlify-specific-context-object)，其中包含有关请求的元数据，例如用户的 IP、地理位置数据和 cookie。

这可以通过 `Astro.locals.netlify.context` 对象访问：

```astro
---
const {
  geo: { city },
} = Astro.locals.netlify.context;
---

<h1>你好，来自{city}的友好访客！</h1>
```

如果你使用 TypeScript，你可以通过更新 `src/env.d.ts` 来使用 `NetlifyLocals` 来 [获得正确的类型](/zh-cn/guides/typescript/#扩展全局类型)：

```ts title="src/env.d.ts"
type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals

declare namespace App {
  interface Locals extends NetlifyLocals {
    // ...
  }
}
```

这不适用于预渲染的页面。

### Netlify 图片 CDN 支持

这个适配器默认使用 [Netlify 图片 CDN](https://docs.netlify.com/image-cdn/overview/) 来实时转换图片，因而不会影响构建时间。它背后是使用 [Astro 图片服务](/zh-cn/reference/image-service-reference/) 实现的。

如果你想退出 Netlify 的图片 CDN 远程图片优化，可以使用 `imageCDN` 选项：

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    imageCDN: false,
  }),
});
```
如果你使用的图片托管在另一个域名上，你必须使用 [`image.domains`](/zh-cn/reference/configuration-reference/#imagedomains) 或 [`image.remotePatterns`](/zh-cn/reference/configuration-reference/#imageremotepatterns) 配置选项授权该域名或 URL 模式：

```js title="astro.config.mjs" ins={7-9}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
    // ...
    adapter: netlify(),
    image: {
      domains: ['example.com'],
    },
});
```
要了解更多信息，请参阅 [授权远程图片的指南](/zh-cn/guides/images/#授权远程图像)。如果图片托管在与你的站点相同的域名上，这不是必需的。

### 使用 Netlify 适配器的静态站点

对于托管在 Netlify 上的静态站点（`output: 'static'`），你通常不需要适配器。然而，某些部署功能只能通过适配器来实现。

静态站点需要安装这个适配器来使用和配置 Netlify 的[图像服务](#netlify-图片-cdn-支持)。

如果你在 Astro 配置中使用了 `redirects` 配置，Netlify 适配器可以将其转换为正确的 `_redirects` 格式。

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify(),
  redirects: {
    '/blog/old-post': '/blog/new-post',
  },
});
```

一旦你运行了 `astro build`，就会有一个 `dist/_redirects` 文件。Netlify 将使用它来正确地路由生产环境中的页面。

:::note
你仍然可以包含一个 `public/_redirects` 文件来手动重定向。你在重定向配置中指定的任何重定向都会被追加到你自己的重定向的末尾。
:::

### Sessions

Astro [Session API](/zh-cn/guides/sessions/) 允许你在请求间，轻松地存储用户数据。该功能可用于用户数据和偏好选项，购物车内容，资格鉴权。不同于 cookie 存储，这里不存在对数据大小的限制，并且可以将其存储在不同的设备上。

当使用 Netlify 适配器时，Astro 将自动配置 [Netlify Blobs](https://docs.netlify.com/blobs/overview/) 用于会话（session）存储。如果你更倾向于使用其他的会话存储驱动，你可以在 Astro config 中指定。更多细节请参见 [`session` 配置参考](/zh-cn/reference/configuration-reference/#sessiondriver)。

### 缓存页面

可以缓存没有任何动态内容的按需渲染页面，以提高性能并降低资源使用率。在适配器中启用 `cacheOnDemandPages` 选项将会缓存所有服务器渲染的页面，最长可达一年：

```ts title="astro.config.mjs" ins={4}
export default defineConfig({
  // ...
  adapter: netlify({
    cacheOnDemandPages: true,
  }),
});
```

这可以通过向你的响应添加缓存头来根据每个页面进行更改：

```astro title="pages/index.astro"
---
import Layout from '../components/Layout.astro';

Astro.response.headers.set('CDN-Cache-Control', 'public, max-age=45, must-revalidate');
---

<Layout title="Astro on Netlify">
  {new Date()}
</Layout>
```

使用 [细粒度缓存控制](https://www.netlify.com/blog/swr-and-fine-grained-cache-control/)，Netlify 支持标准缓存头，例如 `CDN-Cache-Control` 或 `Vary`。请参阅文档，了解如何实现例如 TTL 或 SWR 缓存：https://docs.netlify.com/platform/caching

### 包括或排除 Netlify Functions 中的文件

当使用 Netlify 部署按需渲染的 Astro 网站时，生成功能会自动跟踪并包含服务器依赖。然而，你可能需要自定义哪些文件应该被包含在你的 Netlify Funcitons 中。

#### `includeFiles`

<p>
**类型：** `string[]`<br />
**默认值：** `[]`<br />
<Since v="5.3.0" />
</p>

`includeFiles` 属性允许你明确指定哪些附加的文件是需要和功能一同打包的。该属性对于那些未自动检测到依赖项的文件很有用，例如：
- 使用 `fs` 模块执行加载的数据文件
- 配置文件
- 模板文件

请提供一个数组，其中包含需附加的文件路径，路径需要是相对于项目 [`root`](/zh-cn/reference/configuration-reference/#root) 的相对路径。绝对路径可能会无法正常工作。

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    includeFiles: ['./my-data.json'], // 相对于 `root`
  }),
});
```

#### `excludeFiles`

<p>
**类型：** `string[]`<br />
**默认值：** `[]`<br />
<Since v="5.3.0" />
</p>

你可以使用 `excludeFiles` 属性来避免特定的文件被一同打包，否则其将会被包含在内。该属性有利于：
- 减小打包产物的体积
- 排除大型的二进制文件
- 避免不必要的文件被部署

请提供一个数组，其中包含需要排除的文件路径，路径需要是相对于项目 [`root`](/zh-cn/reference/configuration-reference/#root) 的相对路径。绝对路径可能会无法正常工作。

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    excludeFiles: ['./src/some_big_file.jpg'], // 相对于 `root`
  }),
});
```

#### 使用 glob 模式

不论是 `includeFiles` 还是 `excludeFiles` 都支持使用 [glob 模式](/zh-cn/guides/imports/#glob-模式) 来匹配多项文件：

```js title="astro.config.mjs" ins={7, 10-11}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  adapter: netlify({
    includeFiles: [
      './data/**/*.json'
    ],
    excludeFiles: [
      './node_modules/package/**/*',
      './src/**/*.test.js'
    ]
  }),
});
```


### 本地开发功能

当运行 `astro dev` 时，适配器会启用若干 Netlify 平台功能，以确保开发环境尽可能与生产环境一致。这些功能包括：

- 一个本地的 [Netlify 图像 CDN](https://docs.netlify.com/build/image-cdn/overview/) 服务器。默认情况下用于 [图像支持](#netlify-图片-cdn-支持)
- 一个本地的 [Netlify Blobs](https://docs.netlify.com/build/data-and-storage/netlify-blobs/) 服务器。默认情况下用于 [sessions](#sessions)
- 来自你的 Netlify 配置的 [重定向、重写](https://docs.netlify.com/manage/routing/redirects/overview/) 和 [headers](https://docs.netlify.com/manage/routing/headers/)
- 按需渲染的页面中访问的 [Netlify 边缘上下文](#从你的站点访问-edge-上下文)
- 来自你的 Netlify 站点的 [环境变量](https://docs.netlify.com/build/environment-variables/overview/)

当您的本地站点使用 `netlify link` [链接到 Netlify 站点](https://docs.netlify.com/api-and-cli-guides/cli-guides/get-started-with-cli/#link-and-unlink-sites) 时，这些功能效果最佳。

你可以在适配器配置中的 [`devFeatures`](#devfeatures) 选项启用或禁用其中的一些功能。默认情况下，除环境变量外，所有功能均已启用。

#### `devFeatures`

<p>
**类型：** `boolean | object`<br />
**默认值：** `{ images: true, environmentVariables: false }`<br />
<Since v="6.5.1" pkg="@astrojs/netlify"/>
</p>

`devFeatures` 可以是布尔值，用于启用或禁用所有功能，或者是一个对象，用来启用特定功能。

```js title="astro.config.mjs" ins={7-12}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    devFeatures: {
      // 在开发中启用 Netlify 图像 CDN 支持. 默认为 true。
      images: false, 
      // 在开发环境中注入 Netlify 环境变量。默认值为 false。
      environmentVariables: true, 
    },
  }),
});
```

##### `devFeatures.images`

<p>
**类型：** `boolean`<br />
**默认值：** `true`<br />
<Since v="6.5.1" pkg="@astrojs/netlify"/>
</p>

在开发中启用对本地 [Netlify 图像 CDN](https://docs.netlify.com/build/image-cdn/overview/) 的支持。

这使用的是 Netlify 图像 CDN 的本地版本，而不是默认的 Astro 图像服务。

##### `devFeatures.environmentVariables`

<p>
**类型：** `boolean`<br />
**默认值：** `false`<br />
<Since v="6.5.1" pkg="@astrojs/netlify"/>
</p>

将来自你的 Netlify 站点的环境变量注入到开发环境中。

这使得你可以在开发环境中使用与生产环境相同的值。有关更多信息，包括如何为不同环境使用不同变量，请参阅 [Netlify 关于环境变量的文档](https://docs.netlify.com/build/environment-variables/overview/)。

## 实验性功能

以下功能当前可用，但在未来更新中可能会发生破坏性变更。如果你在项目中使用这些功能，请密切关注 [`@astrojs/netlify` CHANGELOG](https://github.com/withastro/astro/tree/main/packages/integrations/netlify/CHANGELOG.md) 以获取最新动态。


### `experimentalStaticHeaders`

<p>
  **类型：** `boolean` <br />
  **默认值：** `false`<br />
  <Since v="6.4.0"  pkg="@astrojs/netlify"/>
</p>

启用在 Netlify 配置中为预渲染页面指定自定义标头。

启用后，当 Astro 功能（如内容安全策略）提供静态标头时，适配器会将其 [保存在框架 API 配置文件中](https://docs.netlify.com/frameworks-api/#headers)。

例如，当启用 [实验性的内容安全策略](/zh-cn/reference/experimental-flags/csp/) 时，可以使用 `experimentalStaticHeaders` 将 CSP `headers` 添加到你的 Netlify 配置中，而不是创建 `<meta>` 元素：

```js title="astro.config.mjs" {9}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  experimental: {
    csp: true
  },
  adapter: netlify({
    experimentalStaticHeaders: true 
  })
});
```

## 示例

* [Astro Netlify Edge Starter](https://github.com/sarahetter/astro-netlify-edge-starter) 提供了一个示例以及 README 中的指南。
* [浏览 GitHub 上的 Astro Netlify 项目](https://github.com/search?q=path%3A**%2Fastro.config.mjs+%40astrojs%2Fnetlify\&type=code) 查看更多示例！

[astro-integration]: /zh-cn/guides/integrations-guide/
